README.Rmd

---
title: "bootf2: Simulation and Comparison of Dissolution Profiles"
date: "`r format(Sys.Date())`"
output:
  github_document:
    toc: yes
    toc_depth: 3
    number_sections: no
    fig_width: 7
    fig_height: 4.5
bibliography: vignettes/ref.bib
notes-after-punctuation: false
link-citations: yes
csl: vignettes/ref.csl
---

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

```{r setup0, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  collapse = TRUE,
  comment = "#",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

```{r longlinks, echo=FALSE}
lcran <- "https://CRAN.R-project.org/package=bootf2"
```


## Installation{-}

- To install the released version from CRAN:
```{r install-cran, echo=TRUE, eval=FALSE}
install.packages("bootf2", repos = "https://cloud.r-project.org/")
```

- To install the development version from Github, please install
  [Rtools](https://cran.r-project.org/bin/windows/Rtools/) for building R
  packages from sources if you use Windows, then

```{r install, echo=TRUE, eval=FALSE}
# Need devtools. if you don't have it, install.packages("devtools") 
devtools::install_github("zhengguoxu/bootf2")
```

## Introduction

<!-- badges: start -->
<!-- badges: end -->

The package `bootf2` was developed to compare the dissolution profiles using
bootstrap $f_2$ method, as recommended recently by several regulatory 
guidelines [@EMA-2018-09-QA.MSD.DISSO; @Davit-2013-03-BA; @Lum-2019-05-WS; 
@Mandula-2019-05-WS]. Several additional functions were included later for the
simulation of the dissolution profiles.

Currently, there are four main functions in the package:

1. `sim.dp()` to simulate dissolution profiles using mathematical models or
    multivariate normal distribution. See vignette 
    *Simulation of Dissolution Profiles* on [CRAN](`r lcran`) for details.
1. `calcf2()` to calculate similarity factor $f_2$ according to different
    regulatory rules. See vignette *Calculating Similarity Factor $f_2$*
    on [CRAN](`r lcran`) for details.
1. `sim.dp.byf2()` to find a dissolution profile that, when compared to a given
    reference profile, has $f_2$ value equal to the predefined target $f_2$. See
    vignette *Simulation of Dissolution Profiles with Predefined Target $f_2$* 
    on [CRAN](`r lcran`) for details.
1. `bootf2()` to estimate the confidence intervals of $f_2$s using bootstrap
    method. See vignette 
    *Confidence Intervals of f2 Using Bootstrap Method* on [CRAN](`r lcran`)
    for details.

In addition to the vignettes for the main functions, some common topics 
such as regulation rules are discussed in the vignette 
*Introduction to bootf2* on [CRAN](`r lcran`). 

The most basic usage is given below as a brief demonstration. 

## Examples

### Function `sim.dp()`

The complete list of arguments are shown below. Read the function manual with
`?sim.dp` for more details.

```{r simdp-code, eval = FALSE}
dat <- sim.dp(tp, dp, dp.cv, model = c("Weibull", "first-order"),
              model.par = NULL, seed = NULL, n.units = 12L, product,
              max.disso = 100, ascending = FALSE, message = FALSE,
              time.unit = c("min", "h"), plot = TRUE,
              plot.max.unit = 36L, empirical = TRUE, cv.tol = 1e-6)
```

For the most basic use, the function can be run without any user provided 
arguments, e.g., `sim.dp()`. In such case, 12 units of individual dissolution
profiles will be simulated using Weibull model with a typical sampling time
points of 5, 10, 15, 20, 30, 45, and 60 min. A `seed` number will be randomly 
generated, if not provided by the user, and included in the output for
reproducibility purpose. 


```{r simdp-dat}
library(bootf2)
# simulation. simple as that. 
d.ref <- sim.dp(seed = 1234)
```

The output of `sim.dp()` is a list of at least 3 components:

1. `sim.summary`: A *data frame* with summary statistics of all individual
    dissolution profiles.

```{r simdp-sum}
print(d.ref$sim.summary)
```

1. `sim.disso`: A *data frame* with all individual dissolution profiles.
  
```{r simdp-disso}
print(d.ref$sim.disso)
```

1. `sim.info`: A *data frame* with information of the simulation.

```{r simdp-info}
print(d.ref$sim.info)
```

Depending on the argument settings, there *might be* two additional components:

4. `model.par.ind`: A *data frame* of individual model parameters that are used
    to simulate the individual dissolution profiles if mathematical models are
    chosen for the simulation.
  
```{r simdp-modpar}
print(d.ref$model.par.ind)
```

5. `sim.plot`: A plot if `plot = TRUE`.

```{r simdp-plot}
print(d.ref$sim.plot)
```

Simple case like this might be useful in situations such as testing other
programs where data with certain format is needed. In general, to have better
controlled outcomes, argument `tp`, `model`, and `model.par` should be provided.

### Function `calcf2()`

The complete list of arguments are shown below. Read the function manual with
`?calcf2` for more details. In addition, refer to the vignette
*Introduction to bootf2* on [CRAN](`r lcran`) for detailed discussion on
different regulatory requirements regarding to the applicability of $f_2$. 

```{r calcf2-code, eval = FALSE}
calcf2(test, ref, path.in, file.in, path.out, file.out,
       regulation = c("EMA", "FDA", "WHO", "Canada", "ANVISA"),
       cv.rule = TRUE, message = FALSE, min.points = 3L,
       f2.type = c("est.f2", "exp.f2", "bc.f2", "vc.exp.f2",
                   "vc.bc.f2", "all"), both.TR.85 = FALSE,
       digits = 2L, time.unit = c("min", "h"),  plot = TRUE,
       plot.start.time = 0, plot.max.unit = 24L)
```

The minimum required arguments are `test` and `ref`. Data can also be read from
an Excel file. For interactive use, such as the examples below, the `test` and
`ref` should be *data frames with the time as the first column and individual
profiles as the rest columns*. The `sim.disso` data frame in the output of
`sim.dp()` comes with the correct format, as shown above. This is the base 
function used by function `bootf2()`.

```{r calcf2-good}
# simulate a test data
d.test <- sim.dp(seed = 100, plot = FALSE, message = TRUE)

# calculate f2 with default settings
tmp.f2 <- calcf2(d.test$sim.disso, d.ref$sim.disso, message = TRUE)

print(tmp.f2)
```


When the conditions to apply $f_2$ are not fulfilled, the function will stop
and, depending on the details of non-compliance of regulatory rules, show
different error messages. 

```{r calcf2-bad, error=TRUE}
# simulate reference profile with CV% criterion not fulfilled  
d.ref2 <- sim.dp(seed = 456)

# output with error message
calcf2(d.test$sim.disso, d.ref2$sim.disso, message = TRUE)
```

### Function `sim.dp.byf2()`

The complete list of arguments are shown below. Read the function manual with
`?sim.dp.byf2` for more details.

```{r simdpbyf2-code, eval = FALSE}
dat <- sim.dp.byf2(tp, dp, target.f2, seed = NULL, min.points = 3L,
                   regulation = c("EMA", "FDA", "WHO", "Canada", "ANVISA"),
                   model = c("Weibull", "first-order"), digits = 2L,
                   max.disso = 100, message = FALSE, both.TR.85 = FALSE,
                   time.unit = c("min", "h"), plot = TRUE, sim.dp.out,
                   sim.target = c("ref.pop", "ref.median", "ref.mean"),
                   model.par.cv = 50, fix.fmax.cv = 0, random.factor = 3)
```

Given any dissolution profile `dp` at time points `tp`, and target $f_2$ value
(e.g., `target.f2 = 55`), this function will find another dissolution profile
such that when the newly simulated profile is compared to the `dp`, the
calculated $f_2$ will be equal to the target $f_2$. If `target.f2` is provided 
as a range, such as `target.f2 = c(54.95, 55.04)`, then the calculated $f_2$
with simulated profile will be within this range. 

```{r simdpbyf2-dat}
# mean dissolution profile for tp
tp <- c(5, 10, 15, 20, 30, 45, 60)
dp <- c(51, 66, 75, 81, 88, 92, 95)

# find another profile with target f2 = 60
d.t2 <- sim.dp.byf2(tp, dp, target.f2 = 60, seed = 123, message = TRUE)
```

The model parameters in the output are more useful in simulation studies since
they can be used as initial model parameter input to the function `sim.dp()` to
simulate a large population of individual dissolution profiles that have the
known population $f_2$ value when compared to target dissolution profile.

### Function `bootf2()`

The complete list of arguments are shown below. Read the function manual with
`?bootf2` for more details.

```{r bootf2-code, eval = FALSE}
result <- bootf2(test, ref, path.in, file.in, path.out, file.out,
                 n.boots = 10000L, seed = 306L, digits = 2L, alpha = 0.05,
                 regulation = c("EMA", "FDA", "WHO", "Canada", "ANVISA"),
                 min.points = 1L, both.TR.85 = FALSE, print.report = TRUE,
                 report.style = c("concise",  "intermediate", "detailed"),
                 f2.type = c("all", "est.f2", "exp.f2", "bc.f2",
                             "vc.exp.f2", "vc.bc.f2"),
                 ci.type = c("all", "normal", "basic", "percentile",
                             "bca.jackknife", "bca.boot"),
                 quantile.type = c("all", as.character(1:9), "boot"),
                 jackknife.type = c("all", "nt+nr", "nt*nr", "nt=nr"),
                 time.unit = c("min", "h"), output.to.screen = FALSE,
                 sim.data.out = FALSE)
```

The minimum required arguments are dissolution profiles of `test` and `ref`.
The function can output many different 90% confidence intervals for several
$f_2$ estimators. With default settings, the function prints all confidence
intervals for all $f_2$ estimators, and the result will be save in a text file. 

```{r bootf2-out}
# get test and reference data set with correct format
test <- d.test$sim.disso
ref  <- d.ref$sim.disso

# use most default settings (output all) but small number of bootstrap
# to have shorter run time for the example. default n.boots = 10000L
t_vs_r <- bootf2(test, ref, n.boots = 100L, print.report = FALSE,
                 output.to.screen = TRUE)
```

The output of the `bootf2()` is a *list* containing:
1. `boot.ci`: A *data frame* of bootstrap $f_2$ confidence intervals.
1. `boot.f2`: A *data frame* of all individual $f_2$ values for all bootstrap
    data sets. This can be used to make plots for visual presentation.
1. `boot.info`: A *data frame* with detailed information of bootstrap for
    reproducibility purpose, such as all arguments used in the function, time
    points used for calculation of \eqn{f_2}{f2}, and the number of `NA`s.
1. `boot.summary`: A *data frame* with descriptive statistics of the bootstrap
    $f_2$.

And depending on the function settings, it might contains `boot.t` and `boot.r`,
lists of all individual bootstrap data sets for the test and reference products.

## Disclaimer

_**Despite the best efforts the author has put into, the package is offered
without any guarantee of accuracy and absolutely no warranty. 
Validation of the package, especially when it is used in regulatory field, 
is the responsibility of the users. The author accept absolutely no liability
for any financial loss or risk to public health resulting from the use of
this package.**_

## References

<div id="refs"></div>