Fatigue Impairment Prediction Suite (FIPS)

If you are measure sleep behaviour or want to predict fatigue, this package probably can help.

FIPS is an R package that provides researchers and practitioners with a comprehensive set of functions for applying and simulating from bio-mathematical models (BMMs) of fatigue.

FIPS includes a set of functions for transforming sleep and actigraphy data to the data frame structure required for executing BMM simulations (called a FIPS_df). Importantly, FIPS includes a set of functions for simulating from and interpreting several forms of BMM, including the Unified Model and Three Process Model. All models are extendable and include customisable parameters. The core features of FIPS leverage R's flexible S3 class system, making extensions straightforward.

Installation

We have no plans for a CRAN submission. To install the latest version of FIPS:

```r

install.packages('remotes') # if remotes not installed

remotes::install_github("humanfactors/FIPS") ```

Core Features Example

Detailed information regarding the FIPS data formats can be found in the "FIPS Simulation Walkthrough Vignette".

If you require a more manual user-interface to generate the FIPS-df, we have a web application that may help you generate the input CSV: https://github.com/Akhil-Eaga/FIPS-Data-Entry-System.

Step 1: Prior to simulation, FIPS requires sleep history data to be in a special format, called a FIPS_df which contains all the information required for modelling (e.g., time awake, time asleep). This can be created with parse_sleepwake_sequence or parse_sleeptimes.

r my_FIPS_dataframe = FIPS::parse_sleepwake_sequence( seq = unit_sequence, # A binary (1,0) vector epoch = 5, # Epoch in minutes of vector series.start = as.POSIXct("2020-05-21 08:00:00"))

Step 2: To run a model simulation, you use FIPS_simulate, which returns a FIPS_simulation with all model predictions/forecasts generated in the corresponding columns. Note that the formula argument is optional, and sensible defaults will be used if omitted.

```r

Run a simulation with the three process model

TPM.simulation.results = FIPS::FIPSsimulate( FIPSdf = myFIPSdataframe, # A FIPSdf modeltype = "TPM", # Three Process Model pvec = TPMmake_pvec() # Default parameter vector # formula = alertness ~ s + c + u + w # An optional formula for output )

Run a simulation with the unified model

unified.simulation.results = FIPS::FIPSsimulate( FIPSdf = myFIPSdataframe, # A FIPSdf modeltype = "unified", # Unified model pvec = unifiedmake_pvec() # Default parameter vector )
```

``` $ print(TPM.simulation.results)

---

Model Type: TPM Epoch Value: 5 minutes Simulation duration: 60 hours Time points: 721 Parameters used (pvec input): ...[Suppressed for README]...

For descriptions of these parameters, inspect: help(FIPS::TPMmakepvec)

A tibble: 721 x 10

datetime time wakestatus simhours s c w u KSS alertness 1 2020-05-21 08:00:00 8 TRUE 0 7.96 -1.67 -5.72 -0.00274 10.3 6.28 2 2020-05-21 08:05:00 8.08 TRUE 0.0833 7.94 -1.63 -5.04 -0.00549 9.84 6.31 3 2020-05-21 08:10:00 8.17 TRUE 0.167 7.93 -1.59 -4.45 -0.00919 9.47 6.33 4 2020-05-21 08:15:00 8.25 TRUE 0.25 7.91 -1.55 -3.92 -0.0138 9.14 6.35 5 2020-05-21 08:20:00 8.33 TRUE 0.333 7.89 -1.50 -3.46 -0.0194 8.85 6.37 6 2020-05-21 08:25:00 8.42 TRUE 0.417 7.88 -1.46 -3.05 -0.0258 8.59 6.39 7 2020-05-21 08:30:00 8.5 TRUE 0.5 7.86 -1.42 -2.69 -0.0332 8.36 6.41 8 2020-05-21 08:35:00 8.58 TRUE 0.583 7.85 -1.37 -2.37 -0.0415 8.16 6.43 9 2020-05-21 08:40:00 8.67 TRUE 0.667 7.83 -1.32 -2.09 -0.0506 7.98 6.46 10 2020-05-21 08:45:00 8.75 TRUE 0.75 7.81 -1.28 -1.84 -0.0606 7.82 6.48

... with 711 more rows

```

``` $ print(unified.simulation.results)

---

Model Type: unified Epoch Value: 5 minutes Simulation duration: 60 hours Time points: 721 Parameters used (pvec input): ...[Suppressed for README]...

For descriptions of these parameters, inspect: help(FIPS::unifiedmakepvec)

A tibble: 721 x 9

datetime time wakestatus simhours s l c w fatigue 1 2020-05-21 08:00:00 8 TRUE 0 0 0 0.335 1.14 1.38 2 2020-05-21 08:05:00 8.08 TRUE 0.0833 0.0502 0.0206 0.320 1.10 1.37 3 2020-05-21 08:10:00 8.17 TRUE 0.167 0.100 0.0412 0.305 1.06 1.36 4 2020-05-21 08:15:00 8.25 TRUE 0.25 0.150 0.0618 0.291 1.02 1.35 5 2020-05-21 08:20:00 8.33 TRUE 0.333 0.200 0.0824 0.276 0.978 1.34 6 2020-05-21 08:25:00 8.42 TRUE 0.417 0.250 0.103 0.261 0.941 1.33 7 2020-05-21 08:30:00 8.5 TRUE 0.5 0.300 0.123 0.247 0.906 1.32 8 2020-05-21 08:35:00 8.58 TRUE 0.583 0.349 0.144 0.232 0.872 1.31 9 2020-05-21 08:40:00 8.67 TRUE 0.667 0.399 0.164 0.218 0.839 1.30 10 2020-05-21 08:45:00 8.75 TRUE 0.75 0.448 0.185 0.204 0.807 1.29

... with 711 more rows

```

Step 3: You now can access printing, summary and plot methods for the FIPS_simulation object. A detailed tutorial of the plotting functionality for FIPS is provided in the vignettes.

r plot(TPM.simulation.results) summary(TPM.simulation.results) print(TPM.simulation.results)

What are BMMs?

BMMs are a class of biological phenomenological models which are used to predict the neuro-behavioural outcomes of fatigue (e.g., alertness, performance) using sleep-wake history. There are several different BMM implementations, but most have their roots in Borbély's (1982) two process model which stipulates that sleepiness/performance impairment functions in response to two processes: a circadian process and a homeostatic process. BMMs enable hypothesis testing of the latent factors underlying the relationships between sleep, fatigue, and human performance. For example, they enable researchers to estimate the relative contributions of homeostatic processes on fatigue, relative to endogenous circadian processes. These models are also frequently applied by defence and industrial sectors to support system safety as part of broader fatigue management strategies. FIPS is the first open-source BMM framework enabling practitioners to inspect, validate, and ideally extend BMMs.

Critical Model Information

Critical functions, arguments and outputs for each model are summarised in table below:

| Model | Three Process | Unified | |------------------------------|-------------------------|------------------------------| | FIPS_Simulate argument | "TPM" | "unified" | | Parameter vector function | TPM_make_pvec() | unified_make_pvec | | Default formula | alertness ~ s + c + u | fatigue ~ s + I(κappa) * c | | Time varying parameter names | s, c, u, w | s, l, c, w | | Default prediction outputs | KSS, alertness | Fatigue (PVT lapses) |

Hourly Risk Index

The FIPS package is in the process of integrating a novel model, the Hourly Risk Index (HRI), which is currently under pre-alpha testing. This model, developed on the foundation of earlier work by Folkard and Lombardi (2004), Folkard et al. (2006, 2007), and others, offers an estimation of the relative risk of safety incidents tied to different work schedules (Fischer et al., 2017). The HRI improves upon the original Risk Index model by incorporating an hourly detail level, enhancing both its predictive accuracy and application range for risk evaluation and accident analysis (UK Rail Safety and Standards Board, 2015).

While the HRI's implementation is in progress, it is not yet automated to the same standard as other models within FIPS. However, the development team is actively working to optimize and integrate the HRI fully.

The HRI pre-alpha implementation can be found on the HRI-implementation branch. The files under the R directory are under active development. A working implementation of the code can be found in https://github.com/humanfactors/FIPS/blob/HRI-implementation/notes/HRI.R in the HRI-implementation branch.

More about the HRI can be found in Roets and Folkard (2022): https://www.sciencedirect.com/science/article/abs/pii/S0925753522000972 , and Roets and Folkard (2023):  Assessing Railway Traffic Controller Safety with an Hourly Risk Index (taylorfrancis.com).

Contributing and Support

We welcome contributions great or small from the community. It would incredibly useful to receive feedback via Github Issues for anything regarding the package, including: installation issues, bugs or unexpected behaviour, usability, feature requests or inquiries, or even something you don't understand in the tutorials about this class of models more generally. Please file a Github issue for any general support queries too.

Terms for Academic Usage

In addition to the rights stipulated in the GNU Affero GPL-3, we request that all academic work leveraging FIPS provide a direct citation to the software package.

Wilson et al., (2020). FIPS: An R Package for Biomathematical Modelling of Human Fatigue Related Impairment. Journal of Open Source Software, 5(51), 2340, https://doi.org/10.21105/joss.02340

tex @article{Wilson2020, doi = {10.21105/joss.02340}, url = {https://doi.org/10.21105/joss.02340}, year = {2020}, publisher = {The Open Journal}, volume = {5}, number = {51}, pages = {2340}, author = {Micah K. Wilson and Luke Strickland and Timothy Ballard}, title = {FIPS: An R Package for Biomathematical Modelling of Human Fatigue Related Impairment}, journal = {Journal of Open Source Software} }