README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)
options(width = 80)
```

# hrqolr <img src="man/figures/hrqolr.png" align="right" width="120" />

<!-- badges: start -->
[![R-CMD-check](https://github.com/INCEPTdk/hrqolr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/INCEPTdk/hrqolr/actions/workflows/R-CMD-check.yaml)
[![codecov](https://codecov.io/gh/INCEPTdk/hrqolr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/INCEPTdk/hrqolr) 
<!-- ![total downloads from RStudio mirror](https://cranlogs.r-pkg.org/badges/grand-total/hrqolr) -->
<!-- badges: end -->

Package for simulating randomised clinical trials with temporal trajectories of health-related 
quality of life (HRQoL) as the outcome, to quantify effect sizes as single-sampled HRQoL values at 
end of follow-up and as the area under the trajectories. 

Developed as part of the INCEPT (Intensive Care Platform Trial) project (<https://incept.dk/>),
which is primarily supported by a grant from Sygeforsikringen "danmark"
(<https://www.sygeforsikring.dk/>).

## Resources

* [Website](https://inceptdk.github.io/hrqolr/index.html) - stand-alone website with full
package documentation
* [Health-related quality of life trajectories in critical illness: protocol for a Monte Carlo simulation study](https://onlinelibrary.wiley.com/doi/10.1111/aas.14324) -
protocol article in Acta Anaesthesiologica Scandinavica outlining the first scientific study to use `hrqolr`

## Getting started

First, load the package:
```{r}
library(hrqolr)
```

```{r include = FALSE}
# avoid breaking data tables
options(width = 999)
```

The preferred way to design a scenario is by using the `setup_scenario()` function to validate the 
input and give it the right format. Set `verbose = FALSE` to silence the validation results.
```{r}
scenario <- setup_scenario(
	arms = c("A", "B"),
	n_patients = 100,
	sampling_frequency = 14,
	index_hrqol = 0.0,
	first_hrqol = 0.1,
	final_hrqol = c(A = 0.8, B = 0.7),
	acceleration_hrqol = c(A = 1.1, B = 1.0),
	
	mortality = 0.4,
	mortality_dampening = 0.0,
	mortality_trajectory_shape = "exp_decay",
	prop_mortality_benefitters = 0.0
)
```

Getting an overview of the final scenario:
```{r}
scenario
```

With the scenario at hand, we can sample a number of example trajectories and visualise them:
```{r}
example_trajs <- sample_example_trajectories(scenario, n_digits = 3)
plot(example_trajs)
```

`sample_example_trajectories` returns a `ggplot` object, allowing you to fine-tune its appearance for your
needs. For example, breaking apart the trajectories in the arms apart with facets and hide the 
legend (remember to load `ggplot2` first). Here, we also set the arm-level trajectory in black to 
make it stand out better:
```{r}
library(ggplot2) 

plot(example_trajs, arm_aes = list(colour = "black")) +
	facet_wrap(~ arm) +
	theme(legend.position = "none")
```

You can also summarise the trajectories, e.g., with inter-quartile ranges. The ribbons become a bit 
wonky at end of follow-up due to increasingly fewer observations some of which might be low:
```{r}
plot(example_trajs, "summarise", ribbon_percentiles = c(0.25, 0.75))
```

The same scenario specification can, then, be used to simulate a desired number of trials. By 
default `hrqolr` will print progress updates to the console (silence these with `verbose = FALSE`):
```{r}
sims <- simulate_trials(scenario)
```

Just printing the returned object gives an overview:
```{r}
sims
```


The returned object contains quite a lot of interesting information. For example, summary statistics 
by arm:
```{r}
sims$summary_stats
```

--and head-to-head comparisons between the arms:
```{r}
sims$comparisons
```

## Installation

`hrqolr` isn't on CRAN yet but can be installed from GitHub if you have the `remotes` package installed:

```{r eval = FALSE}
# install.packages("remotes") 
remotes::install_github("INCEPTdk/hrqolr")
```

You can also install the **development version** from directly from GitHub. Doing this
requires the `remotes` package installed. The development version may contain
additional features not yet available in the stable CRAN version, but may be unstable or lack documentation.

```{r eval = FALSE}
remotes::install_github("INCEPTdk/hrqolr@dev")
```

## Issues and enhancements

We use the [GitHub issue tracker](https://github.com/INCEPTdk/hrqolr/issues) for
all bug/issue reports and proposals for enhancements. 

## Contributing

We welcome contributions directly to the code to improve performance as well
as new functionality. For the latter, please first explain and motivate it in an
[issue](https://github.com/INCEPTdk/hrqolr/issues).

Changes to the code base should follow these steps:

- [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository
- [Make a branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) with an appropriate name in your fork
- Implement changes in your fork, make sure it passes R CMD check (with neither
errors, warnings, nor notes) and add a bullet at the top of NEWS.md with a short
description of the change, your GitHub handle and the id of the pull request
implementing the change (check the `NEWS.md` file to see the formatting)
- Create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) into the `dev` branch
of `adaptr`

## Citation

If using `hrqolr`, please consider citing it:

```{r include = FALSE}
# ensure citation doesn't go beyond chunk
options(width = 80)
```

```{r}
citation(package = "hrqolr")
```