---
title: "Accessing Force-Time Data (Raw)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Accessing Force-Time Data (Raw)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

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.

```{r access, eval=FALSE }
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()`.

```{r getMyTests, eval=FALSE}
# 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()`:

```{r getRawData, eval=FALSE}
# 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.

```{r S7Object, eval=FALSE}
# 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

```{r ftPlot, eval=FALSE}
# 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.

```{r workflowA, eval=FALSE,message=FALSE}
# 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).

```{r workfowB, eval=FALSE}
# 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:

```{r customTags, eval=FALSE}
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.

```{r deidentified, eval=FALSE}
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.