---
title: "MBNMAtime: Package Overview"
author: "Hugo Pedder"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
bibliography: REFERENCES.bib
vignette: >
  %\VignetteIndexEntry{MBNMAtime: Package Overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  warning = FALSE,
  eval=rmarkdown::pandoc_available("1.12.3")
)

library(MBNMAtime)
library(rmarkdown)
library(knitr)
library(dplyr)
#load(system.file("extdata", "vignettedata.rda", package="MBNMAtime", mustWork = TRUE))
```

## Introduction

This vignette demonstrates how to use `MBNMAtime` to perform meta-analysis of studies with multiple follow-up measurements in order to account for time-course relationships within single or multiple treatment comparisons. This can be performed by conducting Model-Based (Network) Meta-Analysis (MBNMA) to pool relative treatment effects. MBNMA models therefore estimate treatment effects over time (e.g. days, weeks, months).

Including all available follow-up measurements within a study makes use of all the available evidence in a way that maintains connectivity between treatments and explains how the response of the treatment changes over time, thus accounting for heterogeneity and inconsistency that may be present from "lumping" together different time points in a standard Network Meta-Analysis (NMA). All models and analyses are implemented in a Bayesian framework, following an extension of the standard NMA methodology presented by [@lu2004] and are run in JAGS *(version 4.3.1 or later is required if using R version \>= 4.2 with Windows Operating Systems)* [@jags]. For full details of time-course MBNMA methodology see Pedder et al. [-@pedder2019], and a simulation study exploring the statistical properties of the method is reported in Pedder et al. [-@pedder2020].

`MBNMAtime` provides a complete set of functions that allow for meta-analysis of longitudinal time-course data and plotting of a number of informative graphics. Functions are provided for ranking, prediction, and for assessing consistency when modelling using relative effects. The package allows for flexible modelling of either relative or absolute effects interchangeably on different time-course parameters within the same analysis, whilst providing a straightforward syntax with which to define these models.

This package has been developed alongside `MBNMAdose`, a package that allows users to perform dose-response MBNMA to allow for modelling of dose-response relationships between different agents within a network. However, *they should not be loaded into R at the same time* as there are a number of functions with shared names that perform similar tasks yet are specific to dealing with either time-course *or* dose-response data.

Within the vignettes, some models have not been evaluated, or have been run with fewer iterations than would be necessary to achieve convergence and produce valid results in practice. This has been done to speed up computation and rendering of the vignettes.

### Workflow within the package

Functions within `MBNMAtime` follow a clear pattern of use:

1.  Load your data into the correct format using `mb.network()` ([Exploring the data](dataexploration-1.html)
2.  Specify a suitable time-course function and analyse your data using `mb.run()` ([Performing a time-course MBNMA](runmbnmatime-2.html)
3.  Test for consistency using functions like `mb.nodesplit()` ([Checking for consistency](consistencychecking-3.html)
4.  Examine model outputs, such as relative effects, forest plots and treatment rankings ([Model outputs](outputs-4.html)
5.  Use your model to make predictions or estimate treatment effects at specific time-points using `predict()` ([Predictions](predictions-5.html)

At each of these stages there are a number of informative graphs that can be generated to help understand the data and make decisions regarding model fitting.

## Datasets Included in the Package

### Pain relief in osteoarthritis

`osteopain` is from a systematic review of treatments for pain in osteoarthritis, used previously in Pedder et al. [-@pedder2019]. The outcome is pain measured on a continuous scale, and aggregate data responses correspond to the mean WOMAC pain score at different follow-up times. The dataset includes 30 Randomised-Controlled Trials (RCTs), comparing 29 different treatments (including placebo). `osteopain` is a data frame in long format (one row per time point, arm and study), with the variables `studyID`, `time`, `y`, `se`, `treatment` and `arm`.

```{r, echo=FALSE}
kable(head(osteopain), digits=2) 
```

### Alogliptin for lowering blood glucose concentration in type II diabetes

`alog_pcfb` is from a systematic review of Randomised-Controlled Trials (RCTs) comparing different doses of alogliptin with placebo [@langford2016]. The systematic review was simply performed and was intended to provide data to illustrate a statistical methodology rather than for clinical inference. Alogliptin is a treatment aimed at reducing blood glucose concentration in type II diabetes. The outcome is continuous, and aggregate data responses correspond to the mean change in HbA1c from baseline to follow-up in studies of at least 12 weeks follow-up. The dataset includes 14 Randomised-Controlled Trials (RCTs), comparing 5 different doses of alogliptin with placebo (6 different treatments in total). `alog_pcfb` is a data frame in long format (one row per time point, arm and study), with the variables `studyID`, `clinicaltrialGov_ID`, `agent`, `dose`, `treatment`, `time`, `y`, `se`, and `N`.

```{r, echo=FALSE}
kable(head(alog_pcfb), digits=2) 
```

### Tiotropium, Aclidinium and Placebo for maintenance treatment of moderate to severe chronic obstructive pulmonary disease

A dataset from a systematic review of Randomised-Controlled Trials (RCTs) for maintenance treatment of moderate to severe chronic obstructive pulmonary disease (COPD) [@karabis2013]. Data are extracted from [@tallarita2019]. SEs were imputed for three studies, and number of patients randomised were imputed for one study (LAS 39) in which they were missing, using the median standard deviation calculated from other studies in the dataset. The outcome is trough Forced Expiratory Volume in 1 second (FEV1), measured in litres and reported in each study arm as mean change from baseline to follow-up. The dataset includes 13 RCTs, comparing 2 treatments (Tiotropium and Aclidinium) and placebo. `copd` is a data frame in long format (one row per observation, arm and study), with the variables `studyID`, `time`, `y`, `se`, `treatment`, and `n`.

```{r, echo=FALSE}
kable(head(copd), digits=2) 
```

### Body weight reduction in obesity patients

`obesityBW_CFB` is from a systematic review of pharmacological treatments for obesity. The outcome measured is change from baseline in body weight (kg) at different follow-up times. 35 RCTs are included that investigate 26 different treatments (16 agents/agent combinations compared at different doses). `obesityBW_CFB` is a dataset in long format (one row per time point, arm and study), with the variables `studyID`, `time`, `y`, `se`, `N`, `treatment`, `arm`, `treatname`, `agent` and `class`.

`class` is the class of a particular `agent` (e.g. Lipase inhibitor)

```{r, echo=FALSE}
kable(head(obesityBW_CFB), digits=2) 
```

### Serum uric acid concentration in gout

`goutSUA_CFB` is from a systematic review of interventions for lowering Serum Uric Acid (SUA) concentration in patients with gout *[not published previously]*. The outcome is continuous, and aggregate data responses correspond to the mean change from baseline in SUA in mg/dL at different follow-up times. The dataset includes 28 RCTs, comparing 41 treatments (8 agents compared at different doses). `goutSUA_CFB` is a data frame in long format (one row per arm and study), with the variables `studyID`, `time`, `y`, `se`, `treatment`, `arm`, `class` and `treatname`.

```{r, echo=FALSE}
kable(head(goutSUA_CFB), digits=2) 
```


## References