Author: Wojciech Wójciak, Oliver Boix
Date: 2023-06-20

# Upgrading from crmPack version 1.0

#### Wojciech Wójciak, Oliver Boix

#### 20 June 2023

The following vignette describes the changes that were introduced to the `crmPack` package as a result of the package’s refactoring. One row in below tables represents a single-type, consistent change.

## Class and slot changes

### Naming convention motivation

To be close to common R style guidelines (Wickham 2019) and use consistent naming conventions within the `crmPack` package, `CamelCase` notation is used for `class` names, `method` names and constructor function names, and `snake_case` notation is used for `slot` names throughout the package.

### New classes

Category | Name | Comment
--- | --- | ---
Data | DataDA | Time-to-DLT augmented data.
Design | DADesign | Design for data augmentation.
Increments | IncrementsHSRBeta | Limiting further increments using a Hard Safety Rule
Increments | IncrementsRelativeDLTCurrent | Increments control based on relative differences in terms of DLTs.
Model | DALogisticLogNormal | Logistic model with bivariate (log) normal prior and data augmentation.
Model | FractionalCRM | Fractional CRM model.
Model | OneParExpPrior | Standard CRM with an exponential prior on the power parameter.
Model | OneParLogNormalPrior | standard CRM with a normal prior on the log power parameter for the skeleton prior probabilities
Model | ProbitLogNormalRel | Probit regression model with a bivariate normal prior on the intercept and log slope.
Parent model class | ModelParamsNormal | Represents parameters of bivariate normal distribution.
SafetyWindow | SafetyWindowConst | Safety window length used when the `gap` should be kept constant.
SafetyWindow | SafetyWindowSize | Safety window length based on cohort size.
Stopping | StoppingLowestDoseHSRBeta | Stopping based on a Hard Safety Rule using the Beta posterior distribution.
Stopping | StoppingMTDCV | Stopping rule based on precision of MTD which is calculated as the coefficient of variation (CV) of the MTD.
Stopping | StoppingMissingDose | Stopping based on NA returned by next best dose.
Stopping | StoppingSpecificDose | Testing a stopping rule at specific dose of the dose grid and not at the next best dose.
nextBest | NextBestEWOC | Next best dose is the highest possible dose subject to overdose control.
nextBest | NextBestInfTheory | Next best dose that is based on information theory.
nextBest | NextBestMinDist | Next best dose that is based on minimum distance to target probability.
nextBest | NextBestNCRMLoss | Next best dose based on NCRM rule and loss function.
nextBest | NextBestProbMTDLTE | Next best dose that selects the dose with the highest probability of having a toxicity rate less or equal to the toxicity target.
nextBest | NextBestProbMTDMinDist | Next best dose that selects the dose with the highest probability of having a toxicity rate with the smallest distance to the toxicity target.

### Renamed classes

Category | New Name | Old Name | Reason
--- | --- | --- | ---
Increments | IncrementsDoseLevels | IncrementsNumDoseLevels | Harmonization
Increments | IncrementsMin | IncrementMin | Harmonization
Stopping | StoppingMaxGainCIRatio | StoppingGstarCIRatio | Clarification

### Renamed slots

Please note that this list might not be exhaustive. Please always check the relevant class documentation for details.

Class/Constructor* | Slot/Arg† | Comment
--- | --- | ---
Name | Name | New Name |
CohortSizeDLT | DLTintervals | dlt_intervals |
cohortSize | cohort_size |
CohortSizeMax | cohortSizeList | cohort_size_list |
CohortSizeMin | cohortSizeList | cohort_size_list |
CohortSizeRange | cohortSize | cohort_size |
DALogisticLogNormal | C_par | c_par |
conditionalPEM | cond_pem |
Design | PLcohortSize | pl_cohort_size |
DualEndpointBeta | refDoseBeta | ref_dose_beta |
DualEndpointEmax | refDoseEmax | ref_dose_emax |
DualEndpointRW | useRW1 | rw1 |
DualEndpointRW() |  | rw1 | replaces `smooth` string
smooth |  | replaced by `rw1` flag
EffFlexi | several slots | several slots | several slot changed, see man page
EffFlexi() | rw1 |  | replaces `smooth` string
smooth |  | replaced by `rw1` flag
Effloglog | several slots | several slots | several slot changed, see man page
IncrementsDoseLevels (IncrementsNumDoseLevels) |  | basis_level |
IncrementsDoseLevels (IncrementsNumDoseLevels) | maxLevels | levels | change applied also to other dependent classes
IncrementsMin (IncrementMin) | IncrementsList | increments_list | change applied also to other dependent classes
IncrementsRelativeDLT | DLTintervals | dlt_intervals | change applied also to other dependent classes
IncrementsRelativeParts | cleanStart | clean_start | change applied also to other dependent classes
dltStart | dlt_start |
McmcOptions |  | rng_kind | to be used by Random Number Generator in rJAGS
| rng_seed | to be used by Random Number Generator in rJAGS
ModelEff | ExpEff |  | moved to model class method and renamed to `efficacy`
dose |  | moved to model class method
NextBestDualEndpoint |  | target_relative | replaces `scale` string
maxOverdoseProb | max_overdose_prob |
scale |  | replaced by `target_relative` flag
targetThresh | target_thresh |
NextBestMaxGain | DLEDuringTrialtarget | prob_target_drt |
DLEEndOfTrialtarget | prob_target_eot |
NextBestMaxGainSamples | DLEDuringTrialtarget | prob_target_drt |
DLEEndOfTrialtarget | prob_target_eot |
Gstarderive | mg_derive |
TDderive | derive |
NextBestNCRM | maxOverdoseProb | max_overdose_prob |
NextBestTD | targetDuringTrial | prob_target_drt |
targetEndOfTrial | prob_target_eot |
NextBestTDsamples | targetDuringTrial | prob_target_drt |
targetEndOfTrial | prob_target_eot |
StoppingAll | stopList | stop_list |
StoppingAny | stopList | stop_list |
StoppingList | stopList | stop_list |
StoppingMaxGainCIRatio (StoppingGstarCIRatio) | targetEndOfTrial | prob_target |
targetRatio | target_ratio |
StoppingTDCIRatio | targetEndOfTrial | prob_target |
targetRatio | target_ratio |
StoppingTargetBiomarker |  | is_relative | replaces `scale` string
scale |  | replaced by `is_relative` flag
TDDesign | PLcohortSize | pl_cohort_size |
TDsamplesDesign | PLcohortSize | pl_cohort_size |
TITELogisticLogNormal | weightMethod | weight_method |
* Class or class’ user constructor. In the later case the Name/New Name is followed by ().
† Slot in case of the class or argument in case of the class’ user constructor

Strikeout indicates that the class/slot was removed.

## Moved `dose` and `prob` Functions from Slots to Methods

Moved `dose` and `prob` functions from model class slots to model class methods. Example of usage: `dose`/`prob` function as a true dose-DLT/DLT-dose relationship.

### Generate data, define a model and get samples

    library(crmPack)

    empty_data <- Data(doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100))
    my_model <- LogisticNormal(
      mean = c(-0.85, 1),
      cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2)
    )
    my_options <- McmcOptions(burnin = 2, step = 2, samples = 20)
    my_samples <- mcmc(empty_data, my_model, my_options)

### Dose

Here is the example on how the `dose` function can be used in case of different inputs, i.e. model’s parameters samples or in case of a fixed model’s parameters values.

    # Doses reaching a specific target probability of the occurrence of a DLT (equal to 0.3),
    # given a particular models and samples.
    # Every single dose corresponds to one particular sample in `my_samples`.
    dose(0.3, my_model, my_samples)

    ##  [1] 1.961955e+00 2.617251e+00 1.167802e+00 9.021515e-01 4.939584e+01
    ##  [6] 3.553180e-01 1.242371e+00 1.951510e-01 3.314612e-04 1.057962e+00
    ## [11] 1.279596e-01 1.605336e-01 6.247247e+00 1.136980e-01 1.751436e-05
    ## [16] 1.286282e+00 4.448543e-01 5.758316e-01 7.480225e-03 2.235373e+00

    # True dose-DLT relationship.
    # Say that -0.8 and 1 are the true values for models parameters alpha0 and alpha1 respectively.
    # The `true_dose_fun` takes one argument (target probability of the occurrence of a DLT)
    # and computes the corresponding dose, according to the model chosen and given a fixed values
    # of the model's parameters.
    true_dose_fun <- doseFunction(my_model, alpha0 = -0.8, alpha1 = 1)
    true_dose_fun(0.3)

    ## [1] 0.9538033

### Prob

    # Toxicity probabilities for a given dose (equal to 10), model and samples.
    # Every single probability value corresponds to one particular sample in `my_samples`.
    prob(10, my_model, my_samples)

    ##  [1] 0.20299887 0.67591152 0.84483855 0.99797896 0.13960517 0.61031211
    ##  [7] 0.75672870 0.77516896 0.70496299 0.79591087 0.97648866 0.57324073
    ## [13] 0.39108697 0.04453572 0.56254977 0.86844677 0.96364339 0.82987649
    ## [19] 0.83841593 0.20286558

    # True DLT-dose relationship.
    # Say that -0.8 and 1 are the true values for models parameters alpha0 and alpha1 respectively.
    # The `true_prob_fun` takes one argument (the dose) and computes the corresponding
    # toxicity probability, according to the model chosen and given a fixed values
    # of the model's parameters.
    true_prob_fun <- probFunction(my_model, alpha0 = -0.8, alpha1 = 1)
    true_prob_fun(10)

    ## [1] 0.8179597

## New Random Number Generator settings for the MCMC

The Random Number Generator (RNG) settings used by the JAGS for the MCMC are now configured solely through the `McmcOptions` class. The RNG settings are: `RNG type` and the `RNG seed` that corresponds to a given `RNG type`. Find out details in the help page for the `McmcOptions` class. Any RNG-related user settings at the R session level (such us those with `set.seed()`) are ignored by the MCMC sampler.

## New no-argument constructors

To aid software development, new no-argument constructs for all sub-classes of `GeneralModel`, `Increments`, `NextBest` and `Stopping` have been introduced. The names of these constructors take the form `.Default<classname>`, where `<classname>` is the name of the class being created.

These constructors return valid, but not necessarily contextually sensible, objects of the required class. One reason the objects returned may not be contextually sensible is that the constructors take no account of any associated `doseGrid`.

Here are some examples of their use:

    .DefaultStoppingAll()

If all of the following rules are `TRUE`:

- ≥ 3 cohorts dosed: If 3 or more cohorts have been treated.

- P(0.2 ≤ prob(DLE | NBD) ≤ 0.35) ≥ 0.5: If the probability of toxicity at the next best dose is in the range [0.20, 0.35] is at least 0.50.

- ≥ 20 patients dosed: If 20 or more participants have been treated.

    class_name <- "LogisticNormal"
    eval(parse(text = paste0(".Default", class_name, "()")))

A logistic log normal model will describe the relationship between dose and toxicity: \[ p(Tox | d) = f(X = 1 | \theta, d) = \frac{e^{\alpha + \beta \cdot d/d^*}}{1 + e^{\alpha + \beta \cdot d/d^*}} \]where d* denotes a reference dose.

The prior for θ is given by\[ \boldsymbol\theta = \begin{bmatrix}\alpha \\ \beta\end{bmatrix}\sim N \left(\begin{bmatrix}-0.85 \\ 1.00\end{bmatrix} , \begin{bmatrix} 1.00 & -0.50 \\ -0.50 & 1.00\end{bmatrix} \right) \]

The reference dose will be 1.00.

## Handling of `NA` or placebo returned as next dose

For consistent handling how the study is stopped and to facilitate analysis of stop reasons in the operation characteristics, the handling of `NA` and placebo returned by `nextBest` methods is changed. In the previous version of `crmPack` stopping for placebo or `NA` returned by a `nextBest` method was handled automatically in the generic `Stopping` method. This is now moved into a new stopping rule `StoppingMissingDose`. As a consequence, the stopping rule `StoppingMissingDose` must be specified for those `nextBest` methods that can return NA, or when placebo is used. Otherwise the simulation may run into an error if the study is not stopped when `NA` is returned as the next dose. `nextBest` methods that can return `NA` are `NextBestNCRM`, `NextBestNCRMLoss` and `NextBestDualEndpoint`.

## Evaluation of stopping rules at a specific dose

Without further specification, stopping rules are evaluated at the dose returned by the used `nextBest` method. With the new stopping rule `StoppingSpecificDose` it is possible to evaluate stopping rules at any dose. For usage see documentation of `StoppingSpecificDose`.

## Further details in class and methods name changes

### Classes

Class/Constructor* | Slot/Arg† | Comment
--- | --- | ---
Name | New Name | Name | New Name |
| ModelLogNormal |  |  | new parent class for all the models with reference dose and bivariate (log) normal prior on the model parameters
ModelParamsNormal |  |  | represents parameters of bivariate normal distribution
positive_number |  |  | to handle strictly positive valued slots (e.g. `ref_dose` in many model classes)
AllModels |  |  |  |
CohortSizeDLT |  | DLTintervals | intervals |
| cohortSize | cohort_size |
CohortSizeMax |  | cohortSizeList | cohort_sizes |
CohortSizeMin |  | cohortSizeList | cohort_sizes |
CohortSizeRange |  | cohortSize | cohort_size |
DALogisticLogNormal |  | C_par | c_par |
| conditionalPEM | cond_pem |
Design |  | PLcohortSize | pl_cohort_size |
DualEndpointBeta |  | refDoseBeta | ref_dose_beta |
DualEndpointEmax |  | refDoseEmax | ref_dose_emax |
DualEndpointRW |  | useRW1 | rw1 |
DualEndpointRW() |  |  | rw1 | replaces `smooth` string
| smooth |  | replaced by `rw1` flag
EffFlexi |  | several slots | several slots | several slot changed, see man page
EffFlexi() |  |  | rw1 | replaces `smooth` string
| smooth |  | replaced by `rw1` flag
Effloglog |  | several slots | several slots | several slot changed, see man page
GeneralModel |  |  | datanames | moved from `AllModels`
|  | datanames_prior |
IncrementMin | IncrementsMin |  |  |
IncrementsDoseLevels |  |  | basis_level |
| maxLevels | levels | change applied also to other dependent classes
IncrementsMin |  | IncrementsList | increments_list | change applied also to other dependent classes
IncrementsNumDoseLevels | IncrementsDoseLevels |  |  |
IncrementsRelativeDLT |  | DLTintervals | intervals | change applied also to other dependent classes
IncrementsRelativeParts |  | cleanStart | clean_start | change applied also to other dependent classes
| dltStart | dlt_start |
McmcOptions |  |  | rng_kind | to be used by Random Number Generator in rJAGS
|  | rng_seed | to be used by Random Number Generator in rJAGS
Model |  |  |  |
ModelEff |  | ExpEff |  | moved to model class method and renamed to `efficacy`
| dose |  | moved to model class method
NextBestDualEndpoint |  |  | target_relative | replaces `scale` string
| maxOverdoseProb | max_overdose_prob |
| scale |  | replaced by `target_relative` flag
| targetThresh | target_thresh |
NextBestMaxGain |  | DLEDuringTrialtarget | prob_target_drt |
| DLEEndOfTrialtarget | prob_target_eot |
NextBestMaxGainSamples |  | DLEDuringTrialtarget | prob_target_drt |
| DLEEndOfTrialtarget | prob_target_eot |
| Gstarderive | mg_derive |
| TDderive | derive |
NextBestNCRM |  | maxOverdoseProb | max_overdose_prob |
NextBestTD |  | targetDuringTrial | prob_target_drt |
| targetEndOfTrial | prob_target_eot |
NextBestTDsamples |  | targetDuringTrial | prob_target_drt |
| targetEndOfTrial | prob_target_eot |
OneParExpNormalPrior | OneParLogNormalPrior |  |  |
OneParLogNormalPrior |  |  | skel_fun_inv |
| skeletonFun | skel_fun |
| skeletonProbs | skel_probs |
OneParLogNormalPrior() |  | doseGrid | dose_grid |
SafetyWindowConst |  | patientFollow | follow |
| patientFollowMin | follow_min |
| patientGap | gap |
SafetyWindowSize |  | patientFollow | follow |
| patientFollowMin | follow_min |
| patientGap | gap |
| sizeIntervals | size |
StoppingAll |  | stopList | stop_list |
StoppingAny |  | stopList | stop_list |
StoppingGstarCIRatio |  | targetEndOfTrial | prob_target |
| targetRatio | target_ratio |
StoppingMaxGainCIRatio |  |  |
StoppingList |  | stopList | stop_list |
StoppingTDCIRatio |  | targetEndOfTrial | prob_target |
| targetRatio | target_ratio |
StoppingTargetBiomarker |  |  | is_relative | replaces `scale` string
| scale |  | replaced by `is_relative` flag
TDDesign |  | PLcohortSize | pl_cohort_size |
TDsamplesDesign |  | PLcohortSize | pl_cohort_size |
TITELogisticLogNormal |  | weightMethod | weight_method |
* Class or class’ user constructor. In the later case the Name/New Name is followed by ().
† Slot in case of the class or argument in case of the class’ user constructor

Strikeout indicates that the class/slot was removed.

### Methods

Method | Argument | Output Changes | Comment
--- | --- | --- | ---
Name | New Name | Name | New Name |  |
| doseFunction |  |  |  | returns dose computing function for a given model
efficacy |  |  |  | new generic function
probFunction |  |  |  | returns probability computing function for a given model
update-ModelPseudo |  |  |  |
biomLevel |  |  | xLevel |  | added only for generic, reordered arguments for generic and methods
| dose |  |  | changed generic and methods
biomarker |  |  |  | changed generic and methods
biomLevel-DualEndpoint |  | dose |  |  |
dose |  | prob | x |  |
gain |  | several arguments | several arguments |  | several arguments (generic and methods) changed, see man page
getEff |  |  |  | renamed elements in the list returned |
mcmc |  | fromPrior | from_prior |  |
| program |  |  |
| verbose |  |  |
nextBest-NextBestMaxGain |  |  |  | renamed elements in the list returned |
| Effmodel | model_eff |  |
| Effsamples | samples_eff |  |
| SIM | in_sim |  |
nextBest-NextBestMaxGainSamples |  |  |  | renamed elements in the list returned |
| Effmodel | model_eff |  |
| Effsamples | samples_eff |  |
| SIM | in_sim |  |
nextBest-NextBestTD |  | Effmodel | model_eff |  |
| Effsamples | samples_eff |  |
| SIM | in_sim |  |
nextBest-NextBestTDsamples |  | Effmodel | model_eff |  |
| Effsamples | samples_eff |  |
size | size |  | check |  |
update-Data |  |  | check |  |
| newCohort | new_cohort |  |
update-DataDA |  |  | check |  |
update-DataDual |  |  | check |  |
update-DataParts |  |  | check |  |
update-EffFlexi |  |  |  |  | replaced by `update-ModelPseudo`
update-Effloglog |  |  |  |  | replaced by `update-ModelPseudo`
update-LogisticIndepBeta |  |  |  |  | replaced by `update-ModelPseudo`

Strikeout indicates that the method/argument was removed.

## References

Wickham, Hadley. 2019. Advanced r, Second Edition. Chapman & Hall/CRC: R Series. https://adv-r.hadley.nz.