Adding new models
Using a custom model is an advanced option outlined below. This section also serves to aid developers who want to permanently add new models to the package.
Wherever a model, such as bertalanffy or gompertz, appears in TumorGrowth.jl workflows, any function or other callable mymodel can be used, provided it has the right signature. The required signature is mymodel(times, p; ode_options=...), where times is a vector of times and p parameters of the model in the form of a named tuple, such as p = (; v0=0.03, ω= 1.5); ode_options are options to be passed to the ODE solver (see below). The return value of mymodel will be the corresponding volumes predicted by the model.
If the implementation of mymodel requires numerically solving an ordinary differential equation, follow the example given for the bertalanffy2 model, which appears here. (In the TumorGrowth.jl repository, the model ODEs themselves are defined by functions ending in _ode or _ode! in a separate file.)
Additionally, one may want to overload some of functions listed below for the new model, especially if convergence during calibration is an issue. For example, if the new model is a function is called mymodel, and there are two parameters a and b, then you overload guess_parameters like this:
function TumorGrowth.guess_parameters(times, volumes, ::typeof(mymodel))
< code to guess parameters `a` and `b` >
return (; a=a, b=b)
end Optional methods for new model implementations
TumorGrowth.guess_parameters — Functionguess_parameters(times, volumes, model)Apply heuristics to guess parameters p for a model.
New model implementations
Fallback returns nothing which will prompt user's to explicitly specify initial parameter values in calibration problems.
TumorGrowth.lower_default — Functionlower_default(model)Return a named tuple with the lower bound constraints on parameters for model.
For example, a return value of (v0 = 0.1,) indicates that p.v0 > 0.1 is a hard constraint for p, in calls of the form model(times, p), but all other components of p are unconstrained.
New model implementations
Fallback returns NamedTuple().
TumorGrowth.upper_default — Functionupper_default(model)Return a named tuple with the upper bound constraints on the parameters for model.
For example, a return value of (v0 = 1.0,) indicates that p.v0 < 1.0 is a hard constraint for p, in calls of the form model(times, p), but all other components of p are unconstrained.
New model implementations
Fallback returns empty named tuple.
TumorGrowth.frozen_default — Functionfrozen_default(model)Return a named tuple indicating parameter values to be frozen by default when calibrating model. A value of nothing for a parameter indicates freezing at initial value.
New model implementations
Fallback returns an empty named tuple.
TumorGrowth.optimiser_default — Functionoptimiser_default(model)Return the default choice of optimiser for model.
New model implementations
Must return an optimiser from Optimisers.jl, or an optimiser with the same API, or one of the optimisers from LeastSquaresOptim.jl, such as LevenbergMarquardt() or Dogleg().
The fallback returns Optimisers.Adam(0.0001).
TumorGrowth.scale_default — Functionscale_default(times, volumes, model)Return an appropriate default for a function p -> f(p) so that p = f(q) has a value of the same order of magnitude expected for parameters of model, whenever q has the same form as p but with all values equal to one.
Ignored by the optimisers LevenbergMarquardt() and Dogleg().
New model implementations
Fallback returns the identity.
TumorGrowth.penalty_default — Functionpenalty_default(model)Return the default loss penalty to be used when calibrating model. The larger the positive value, the more calibration discourages large differences in v0 and v∞ on a log scale. Helps discourage v0 and v∞ drifting out of bounds in models whose ODE have a singularity at the origin.
Ignored by the optimisers LevenbergMarquardt() and Dogleg().
New model implementations
Must return a value in the range $[0, ∞)$, and will typically be less than 1.0. Only implement if model has strictly positive parameters named v0 and v∞.
Fallback returns 0.
TumorGrowth.radius_default — Functionradius_default(model, optimiser)Return the default value of radius when calibrating model using optimiser. This is the initial trust region radius, which is named Δ in LeastSquaresOptim.jl documentation and code.
This parameter is ignored unless optimiser, as passed to the CalibrationProblem, is LevenbergMarquardt() or Dogleg().
New model implementations
The fallback returns:
10.0ifoptimiser isaLevenbergMarquardt`1.0ifoptimiser isaDogleg`0otherwise
TumorGrowth.iterations_default — Functioniterations_default(model, optimiser)Number of iterations, when calibrating model and using optimiser, to be adopted by default in model comparisons. Here optimiser is an optimiser from Optimisers.jl, or implements the same API, or is one of: LevenbergMarquardt(), or Dogleg(). .
New model implementations
Fallback returns 10000, unless optimiser isa Union{LevenbergMarquardt,Dogleg}, in which case 0 is returned (stopping controlled by LeastSquaresOptim.jl).