Prepare Sports Injury Data
In injurytools: A Toolkit for Sports Injury Data Analysis

library(knitr)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
options(rmarkdown.html_vignette.check_title = FALSE) # to supress R-CMD check

## to fold/hook the code
hook_output <- knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
   lines <- options$output.lines
   if (is.null(lines)) {
     return(hook_output(x, options))  # pass to default hook
   }
   x <- unlist(strsplit(x, "\n"))
   more <- "..."
   if (length(lines) == 1) {
     if (length(x) > lines) {
       # truncate the output, but add ....
       x <- c(head(x, lines), more)
     }
   } else {
     x <- c(if (abs(lines[1]) > 1) more else NULL,
            x[lines],
            if (length(x) > lines[abs(length(lines))]) more else NULL
           )
   }
   # paste these lines together
   x <- paste(c(x, ""), collapse = "\n")
   hook_output(x, options)
 })

library(injurytools)
library(dplyr)

Data preprocessing is the very first step one has to follow, every time one wants to analyze sports injury data using injurytools R package.

This document briefly shows how to use the functions intended to facilitate this data preprocessing step and what the final data set is like.

Starting point

Data can be collected in several ways and by several means. A conventional manner is to collect and store data as events occur. So, with regard to sports medicine, it is common to store injury records on one hand, and on the other side, data related to training and competitions/matches (exposure time among others) in a separate table. Following this, we consider that the user has the raw data in two separate data sets that we call injury and exposure data, respectively[^prepare-note-1].

[^prepare-note-1]: If the data are not recorded this way, we suggest splitting both information into separate tables and then following the same functions provided by the package.

1) prepare and standardize injury and exposure data

Thus the early task is to tidy up these two sources of data.

As example data sets we consider raw_df_injuries and raw_df_exposures data sets available from the injurytools package. These are data of Liverpool Football Club male's first team players over two consecutive seasons, 2017-2018 and 2018-2019, scrapped from https://www.transfermarkt.com/ website:

head(raw_df_injuries)
head(raw_df_exposures)

We standardize the key column names such as: player (subject) identifier, dates of injury and recovery (if any), training/match/season date and amount of time of exposure. And set them proper names and formats by means of prepare_inj() and prepare_exp()[^prepare-note-2].

[^prepare-note-2]: The date argument should be either of class Date, given in "%Y-%m-%d" format, or of class integer/numeric, a 4-digit integer referring to year in which the season started.

df_injuries <- prepare_inj(df_injuries0   = raw_df_injuries,
                           player         = "player_name",
                           date_injured   = "from",
                           date_recovered = "until")

df_exposures <- prepare_exp(df_exposures0 = raw_df_exposures,
                            player        = "player_name",
                            date          = "year",
                            time_expo     = "minutes_played")

We suggest collecting exposure time on as fine scale as possible, i.e. minutes would be the desired unit as the total time spent training and participating in competitions/matches. However, if the units are "seasons", then do:

See the R-code

## a possible way for the case where each row in exposure data correspond to a
## season and there is no more information about time of exposure
raw_df_exposures$time_expo_aux <- 1 
df_exposures2 <- prepare_exp(df_exposures0 = raw_df_exposures,
                             player        = "player_name",
                             date          = "year",
                             time_expo     = "time_expo_aux")

## note 'tstart_s' and 'tstop_s' columns
injd <-  prepare_all(data_exposures = df_exposures2,
                     data_injuries  = df_injuries,
                     exp_unit = "seasons")
head(injd)

2) integrate both sources of data

Then, we apply prepare_all() to the data sets tidied up above. It is important to specify the unit of exposure, i.e. the exp_unit argument, which must be one of "minutes", "hours", "days", "matches_num", "matches_minutes", "activity_days" or "seasons".

injd <-  prepare_all(data_exposures = df_exposures,
                    data_injuries  = df_injuries,
                    exp_unit = "matches_minutes")
head(injd)
# injd |> 
#   group_by(player) |> 
#   slice(1, n())

The outcome is a prepared data set, structured in a suitable way that is ready for its use by statistical modelling approaches. These data set will always have the columns listed below (standardized columns or created by the function), as well as further (optional) sports-related variables.

player: player identifier.
t0 and tf: the follow-up period of the corresponding player, i.e. player's first and last dates observed (same value for each player).
date_injured and date_recovered: dates of injury and recovery of the corresponding observation (if any). Otherwise NA.
tstart and tstop: beginning and ending dates of the corresponding interval in which the observation has been at risk of injury.
tstart_xand tstop_x: beginning and ending times of the corresponding interval in which the observation has been at risk of injury (it depends on the unit of exposure time specified).
status: injury (event) indicator.
enum: an integer indicating the recurrence number, i.e. the $k$-th injury (event), at which the observation is at risk.
days_lost: number of days lost due to injury occurred at tstop/date_injured (if any; otherwise 0), i.e. date_recovered - date_injured in days.

For example the first row of injd corresponds to the player Adam Lallana, to the risk set that starts on 2017-07-01 and ends on 2017-07-31, after having played 236 minutes, when he got firstly (enum = 1) injured (status = 1). The second row corresponds to the risk set of being injured by a second injury (enum = 2), the set starts when he was fully recovered in 2017-11-23 and finishes when he suffered another hamstring injury[^prepare-note-3].

[^prepare-note-3]: The fact that tstart equals tstop is due to the player did not participate and had no minutes playing a match in that period of time. Note that this will cause problems if one wants to use survival analysis techniques. Possible alternatives: use another exposure time unit, or add a small number of minutes (e.g. 0.5)...

The prepared data set, an `injd` object

These final data set it's an R object of class injd,

class(injd)

and have the following attributes:

str(injd, 1)

unit_exposure: a character indicating the unit of exposure time used in this object.
follow_up: a data frame consisting of one row per player with their first and last dates observed (t0 and tf columns).
data_exposures: the preprocessed exposure data frame.
data_injuries: the preprocessed injury data frame.