shorts (version 3.2.0)

model_functions: Model functions

Description

Family of functions that serve a purpose of estimating short sprint parameters

model_in_situ estimates short sprint parameters using velocity-acceleration trace, provided by the monitoring systems like GPS or LPS. See references for the information

model_radar_gun estimates short sprint parameters using time-velocity trace, with additional parameter TC serving as intercept

model_laser_gun alias for model_radar_gun

model_tether estimates short sprint parameters using distance-velocity trace (e.g., tether devices).

model_tether_DC estimates short sprint parameters using distance-velocity trace (e.g., tether devices) with additional distance correction DC parameter

model_time_distance estimates short sprint parameters using time distance trace

model_time_distance_FD estimates short sprint parameters using time-distance trace with additional estimated flying distance correction parameter FD

model_time_distance_FD_fixed estimates short sprint parameters using time-distance trace with additional flying distance correction parameter FD which is fixed by the user

model_time_distance estimates short sprint parameters using time distance trace with additional time correction parameter TC

model_time_distance estimates short sprint parameters using time distance trace with additional distance correction parameter DC

model_time_distance estimates short sprint parameters using time distance trace with additional time correction TC and distance correction TC parameters

model_timing_gates estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells)

model_timing_gates_TC estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells), with additional time correction parameter TC

model_timing_gates_FD estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells), with additional estimated flying distance correction parameter FD

model_timing_gates_FD_fixed estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells), with additional flying distance correction parameter FD which is fixed by the user

model_timing_gates_DC estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells), with additional distance correction parameter DC

model_timing_gates_TC_DC estimates short sprint parameters using distance-time trace (e.g., timing gates/photo cells), with additional time correction TC and distance correction DC parameters

Usage

model_in_situ(
  velocity,
  acceleration,
  weights = 1,
  velocity_threshold = NULL,
  velocity_step = 0.2,
  n_observations = 2,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_radar_gun(
  time,
  velocity,
  weights = 1,
  CV = NULL,
  use_observed_MSS = FALSE,
  na.rm = FALSE,
  ...
)
model_laser_gun(
  time,
  velocity,
  weights = 1,
  CV = NULL,
  use_observed_MSS = FALSE,
  na.rm = FALSE,
  ...
)
model_tether(
  distance,
  velocity,
  weights = 1,
  CV = NULL,
  use_observed_MSS = FALSE,
  na.rm = FALSE,
  ...
)
model_tether_DC(
  distance,
  velocity,
  weights = 1,
  CV = NULL,
  use_observed_MSS = FALSE,
  na.rm = FALSE,
  ...
)
model_time_distance(time, distance, weights = 1, CV = NULL, na.rm = FALSE, ...)
model_time_distance_FD(
  time,
  distance,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_time_distance_FD_fixed(
  time,
  distance,
  weights = 1,
  FD = 0,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_time_distance_TC(
  time,
  distance,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_time_distance_DC(
  time,
  distance,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_time_distance_TC_DC(
  time,
  distance,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_timing_gates(distance, time, weights = 1, CV = NULL, na.rm = FALSE, ...)
model_timing_gates_TC(
  distance,
  time,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_timing_gates_FD(
  distance,
  time,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_timing_gates_FD_fixed(
  distance,
  time,
  weights = 1,
  FD = 0,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_timing_gates_DC(
  distance,
  time,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)
model_timing_gates_TC_DC(
  distance,
  time,
  weights = 1,
  CV = NULL,
  na.rm = FALSE,
  ...
)

Value

List object with the following elements:

data

Data frame used to estimate the sprint parameters

model_info

Extra information regarding model used

model

Model returned by the nlsLM function

parameters

List with the following estimated parameters: MSS, MAC, TAU, and PMAX

correction

List with additional model correcitons

predictions

Data frame with .predictor, .observed, .predicted, and .residual columns

model_fit

List with multiple model fit estimators

CV

If cross-validation is performed, this will included the data as above, but for each fold

Arguments

weights

Numeric vector. Default is 1

velocity_threshold

Velocity cutoff. If NULL (default), velocity of the observation with the fastest acceleration is taken as the cutoff value

velocity_step

Velocity increment size for finding max acceleration. Default is 0.2 m/s

n_observations

Number of top acceleration observations to keep in velocity bracket. Default is 2

CV

Should cross-validation be used to estimate model fit? Default is NULL. Otherwise use integer indicating number of folds

na.rm

Logical. Default is FALSE

...

Forwarded to nlsLM function

time, velocity, distance, acceleration

Numeric vector

use_observed_MSS

Should observed peak velocity be used as MSS parameter? Default is FALSE

FD

Flying distance parameter. Default is 0

References

Samozino P. 2018. A Simple Method for Measuring Force, Velocity and Power Capabilities and Mechanical Effectiveness During Sprint Running. In: Morin J-B, Samozino P eds. Biomechanics of Training and Testing. Cham: Springer International Publishing, 237–267. DOI: 10.1007/978-3-319-05633-3_11.

Clavel, P., Leduc, C., Morin, J.-B., Buchheit, M., & Lacome, M. (2023). Reliability of individual acceleration-speed profile in-situ in elite youth soccer players. Journal of Biomechanics, 153, 111602. https://doi.org/10.1016/j.jbiomech.2023.111602

Morin, J.-B. (2021). The “in-situ” acceleration-speed profile for team sports: testing players without testing them. JB Morin, PhD – Sport Science website. Accessed 31. Dec. 2023. https://jbmorin.net/2021/07/29/the-in-situ-sprint-profile-for-team-sports-testing-players-without-testing-them/

Examples

# Model In-Situ (Embedded profiling)
data("LPS_session")
m1 <- model_in_situ(
  velocity = LPS_session$velocity,
  acceleration = LPS_session$acceleration,
  # Use specific cutoff value
  velocity_threshold = 4)
m1
plot(m1)


# Model Radar Gun (includes Time Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 6, 0.1))

# Add some noise
df$velocity <- df$velocity + rnorm(n = nrow(df), 0, 10^-2)

m1 <- model_radar_gun(time = df$time, velocity = df$velocity)
m1
plot(m1)


# Model Laser Gun (includes Time Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 6, 0.1))

# Add some noise
df$velocity <- df$velocity + rnorm(n = nrow(df), 0, 10^-2)

m1 <- model_laser_gun(time = df$time, velocity = df$velocity)
m1
plot(m1)


# Model Tether
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 6, 0.5))
m1 <- model_tether(distance = df$distance, velocity = df$velocity)
m1
plot(m1)


# Model Tether with Distance Correction (DC)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0.001, 6, 0.5), DC = 5)
m1 <- model_tether_DC(distance = df$distance, velocity = df$velocity)
m1
plot(m1)


# Model Time-Distance trace (simple, without corrections)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5))
m1 <- model_time_distance(time = df$time, distance = df$distance)
m1
plot(m1)


# Model Time-Distance trace (with Flying Distance Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5), FD = 0.5)
m1 <- model_time_distance_FD(time = df$time, distance = df$distance)
m1
plot(m1)


# Model Time-Distance trace (with Flying Distance Correction fixed)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5), FD = 0.5)
m1 <- model_time_distance_FD_fixed(time = df$time, distance = df$distance, FD = 0.5)
m1
plot(m1)


# Model Time-Distance trace (with Time Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5), TC = 1.5)
m1 <- model_time_distance_TC(time = df$time, distance = df$distance)
m1
plot(m1)


# Model Time-Distance trace (with Distance Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5), DC = -5)
m1 <- model_time_distance_DC(time = df$time, distance = df$distance)
m1
plot(m1)


# Model Time-Distance trace (with Time and Distance Corrections)
df <- create_sprint_trace(MSS = 8, MAC = 6, time = seq(0, 5, by = 0.5), TC = -1.3, DC = 5)
m1 <- model_time_distance_TC_DC(time = df$time, distance = df$distance)
m1
plot(m1)


# Model Timing Gates (simple, without corrections)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40))
m1 <- model_timing_gates(distance = df$distance, time = df$time)
m1
plot(m1)


# Model Timing Gates (with Time Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40), TC = 0.2)
m1 <- model_timing_gates_TC(distance = df$distance, time = df$time)
m1
plot(m1)


# Model Timing Gates (with Flying Distance Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40), FD = 0.5)
m1 <- model_timing_gates_FD(distance = df$distance, time = df$time)
m1
plot(m1)


# Model Timing Gates (with Flying Distance Correction fixed)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40), FD = 0.5)
m1 <- model_timing_gates_FD_fixed(distance = df$distance, time = df$time)
m1
plot(m1)


# Model Timing Gates (with Distance Correction)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40), DC = 1.5)
m1 <- model_timing_gates_DC(distance = df$distance, time = df$time)
m1
plot(m1)


# Model Timing Gates (with Time and Distance Corrections)
df <- create_sprint_trace(MSS = 8, MAC = 6, distance = c(5, 10, 20, 30, 40), TC = 0.25, DC = 1.5)
m1 <- model_timing_gates_TC_DC(distance = df$distance, time = df$time)
m1
plot(m1)