--- title: "Upgrading from crmPack version 1.0" author: "Wojciech Wójciak, Oliver Boix" date: "20 June 2023" output: rmarkdown::html_vignette bibliography: vignettes.bib vignette: > %\VignetteIndexEntry{Upgrading from crmPack version 1.0} %\VignetteEngine{knitr::rmarkdown} %\VignetteDepends{crmPack} \usepackage[utf8]{inputenc} --- 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 [@advancedR] 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.
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.
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	StoppingMissingDose	Stopping based on NA returned by next best dose.
Stopping	StoppingMTDCV	Stopping rule based on precision of MTD which is calculated as the coefficient of variation (CV) of the MTD.
Stopping	StoppingSpecificDose	Testing a stopping rule at specific dose of the dose grid and not at the next best dose.

### 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	cohortSize	cohort_size
CohortSizeDLT	DLTintervals	dlt_intervals
CohortSizeMax	cohortSizeList	cohort_size_list
CohortSizeMin	cohortSizeList	cohort_size_list
CohortSizeRange	cohortSize	cohort_size
DALogisticLogNormal	C_par	c_par
DALogisticLogNormal	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
DualEndpointRW()	smooth		replaced by `rw1` flag
EffFlexi	several slots	several slots	several slot changed, see man page
EffFlexi()	rw1		replaces `smooth` string
EffFlexi()	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
IncrementsRelativeParts	dltStart	dlt_start
McmcOptions		rng_kind	to be used by Random Number Generator in rJAGS
McmcOptions		rng_seed	to be used by Random Number Generator in rJAGS
ModelEff	dose		moved to model class method
ModelEff	ExpEff		moved to model class method and renamed to `efficacy`
NextBestDualEndpoint		target_relative	replaces `scale` string
	maxOverdoseProb	max_overdose_prob
	scale		replaced by `target_relative` flag
	targetThresh	target_thresh
NextBestMaxGain	DLEDuringTrialtarget	prob_target_drt
NextBestMaxGain	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
NextBestTD	targetEndOfTrial	prob_target_eot
NextBestTDsamples	targetDuringTrial	prob_target_drt
NextBestTDsamples	targetEndOfTrial	prob_target_eot
StoppingAll	stopList	stop_list
StoppingAny	stopList	stop_list
StoppingList	stopList	stop_list
StoppingMaxGainCIRatio (StoppingGstarCIRatio)	targetEndOfTrial	prob_target
StoppingMaxGainCIRatio (StoppingGstarCIRatio)	targetRatio	target_ratio
StoppingTargetBiomarker		is_relative	replaces `scale` string
StoppingTargetBiomarker	scale		replaced by `is_relative` flag
StoppingTDCIRatio	targetEndOfTrial	prob_target
StoppingTDCIRatio	targetRatio	target_ratio
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 ``` r 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. ``` r # 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.34841076 0.11025416 0.86730537 1.53660845 1.20567406 0.83567002 #> [7] 1.64091143 2.28460821 4.52450730 1.44885220 1.58322190 0.02608328 #> [13] 1.21766897 0.39543888 1.28366789 0.73875076 19.61886830 0.60780362 #> [19] 0.05915204 1.29433795 # 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 ``` r # 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.93817478 0.22611044 0.99172210 0.73879550 0.86176537 0.02110999 #> [7] 0.78785107 0.66024799 0.16678261 0.89131170 0.99387321 0.78392448 #> [13] 0.87738055 0.95835853 0.92685442 0.74505590 0.36538941 0.93118090 #> [19] 0.83881343 0.98010014 # 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`, where `` 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: ``` r .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. ``` r 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^*}} $$\n where d* denotes a reference dose. The prior for θ is given by\n$$ \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) $$ \n\n 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		cohortSize	cohort_size
CohortSizeDLT		DLTintervals	intervals
CohortSizeMax		cohortSizeList	cohort_sizes
CohortSizeMin		cohortSizeList	cohort_sizes
CohortSizeRange		cohortSize	cohort_size
DALogisticLogNormal		C_par	c_par
DALogisticLogNormal		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
DualEndpointRW()		smooth		replaced by `rw1` flag
EffFlexi		several slots	several slots	several slot changed, see man page
EffFlexi()			rw1	replaces `smooth` string
EffFlexi()		smooth		replaced by `rw1` flag
Effloglog		several slots	several slots	several slot changed, see man page
GeneralModel			datanames	moved from `AllModels`
GeneralModel			datanames_prior
IncrementMin	IncrementsMin
IncrementsDoseLevels			basis_level
IncrementsDoseLevels		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
IncrementsRelativeParts		dltStart	dlt_start
McmcOptions			rng_kind	to be used by Random Number Generator in rJAGS
McmcOptions			rng_seed	to be used by Random Number Generator in rJAGS
Model
ModelEff		dose		moved to model class method
ModelEff		ExpEff		moved to model class method and renamed to `efficacy`
NextBestDualEndpoint			target_relative	replaces `scale` string
		maxOverdoseProb	max_overdose_prob
		scale		replaced by `target_relative` flag
		targetThresh	target_thresh
NextBestMaxGain		DLEDuringTrialtarget	prob_target_drt
NextBestMaxGain		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
NextBestTD		targetEndOfTrial	prob_target_eot
NextBestTDsamples		targetDuringTrial	prob_target_drt
NextBestTDsamples		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
StoppingTargetBiomarker			is_relative	replaces `scale` string
StoppingTargetBiomarker		scale		replaced by `is_relative` flag
StoppingTDCIRatio		targetEndOfTrial	prob_target
StoppingTDCIRatio		targetRatio	target_ratio
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
nextBest-NextBestTDsamples		Effsamples	samples_eff
size	size		check
update-Data			check
update-Data		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