mutable struct BioPhysParams{T<:Number}

Biophysical parameters to use in forward simulations.

Fields

• kon: A –> B rate, units of (μM s)⁻¹

• koff: B –> A rate, units of s⁻¹

• konb: A+B –> C rate, units of s⁻¹

• reach: Reach of A+B –> C reaction, units of nm

• CP: CP factor (default = 1.0)

• antigenconcen: Concentration of antigen (default = DEFAULT_SIM_ANTIGENCONCEN μM)

• antibodyconcen: Concentration of antibodies, should be consistent with kon's units (default = 1.0 μM)

biopars_from_fitting_vec(p; antibodyconcen=1.0, antigenconcen=1.0)

Generate a BioPhysParams struct from a parameter vector from fitting.

Notes:

• Assumed that $p = [\log_{10}(\text{kon}), \log_{10}(\text{koff}), \log_{10}(\text{kon}_{\text{b}}), \text{reach}, \log_{10}(\text{CP})]$

mutable struct SimParams{T<:Number, DIM}

Biophysical parameters to use in forward simulations.

Fields

• N: Number of particles (default = 1000)

• tstop: Time to end simulations at (default = 600.0)

• tstop_AtoB: Time to turn off A –> B reaction, i.e. time the antibody bath is removed. (default = Inf)

• tsave: Times to save data at (default = nothing)

• L: Domain Length

• initlocs: Initial Particle Positions (default = uniform in $[-L/2,L/2]^{\text{DIM}}$)

• resample_initlocs: Resample initlocs every simulation (default = true)

• nsims: Number of simulations in runsim (to control sampling error) (default = 1000)

Keyword Arguments:

• All fields have a corresponding kwarg.
• antigenconcen = DEFAULT_SIM_ANTIGENCONCEN, the default antigenconcen in units of (nm)⁻³ (unless using convert_agc_units=false).
• DIM = 3 the dimension of the underlying space (i.e. 2 or 3).
• convert_agc_units = true, set to false to disable the conversion of the antigen units from assumed units of μM to (nm)⁻³, see below. In this case $L$ is calculated using the antigen concentration value directly.
• resample_initlocs = true, if set to false initlocs will be constant, simply reusing the initial value sampled in the SimParams constructor.

Notes:

• Uses the antigen concentration to determine $L$, and so needs to be updated if this concentration changes. The antigen concentration is first converted from assumed units of μM to units of (nm)⁻³. Then

  \[ L = \left(\frac{N}{[\text{antigen}] \text{ in (nm)}^{-3}}\right)^{\tfrac{1}{DIM}}\]

run_spr_sim!(outputter, biopars::BioPhysParams, simpars::SimParams,
             terminator = SimNumberTerminator())

Runs a set of SPR simulations via the particle model for a fixed set of physical parameters.

Notes:

• Use the passed BioPhysParams and SimParams to set simulation parameters (including number of simulations).
• Use the outputter to specify a callback controlling what data is saved.
• Use the terminator to specify a callback controlling when the simulation is stopped.

struct TotalBoundOutputter{T}

Callback that saves the amount of bound antibodies (i.e. monovalently + bivalently bound) at each save time.

Fields

• bindcnt

struct TotalAOutputter{T}

Callback that saves the amount of unbound antigen at each save time.

Fields

• bindcnt

means(o::TotalBoundOutputter)

Vector of means.

means(o::TotalAOutputter)

Vector of means.

means!(m, o::TotalBoundOutputter)

In-place vector of means.

vars(o::TotalBoundOutputter)

Vector of variances.

means(o::TotalBoundOutputter)

Vector of standard errors.

mutable struct SimNumberTerminator

Callback that stops simulating when the desired number of simulations is reached.

Fields

• num_completed_sims: How many simulations have been completed

mutable struct VarianceTerminator

Callback that stops simulating when the variance in bound antibodies becomes sufficiently small or a maximum number of simulations is reached.

Fields

• ssetol: The tolerance below which to stop simulating (default = .01).

• notdone: True if should keep iterating.

• minsims: Minimum number of sims to run (default = 15).

• maxsims: Maximum number of sims to run (default = 250).

struct AlignedData

The aligned data from a set of SPR experiments varying antibody concentrations.

Fields

• times: times[i] gives the SPR data timepoints for antibodyconcen[i]

• refdata: refdata[i] gives the SPR simulation data for antibodyconcens[i]

• antibodyconcens: Antibody concentrations for the SPR data set in μM

• antigenconcen: Antigen concentration for the SPR data set in μM

get_aligned_data(fname, antigenconcen)

Read the given CSV file representing aligned SPR data. Returns an AlignedData structure storing the given SPR experiment data.

Notes:

• antigenconcen = nothing the concentration of antigen used in the experiments in units of μM. If not set assumes the CSV filename has the form ""text-AGCCONCEN_aligned.csv"", and parses the number antigen concentration from AGCCONCEN.

struct SurrogateParams{T<:Number}

Biophysical parameters used in the surrogate.

Fields

• logkon_range: log₁₀ space range of kon, first order rate in surrogate (units of s⁻¹).

• logkoff_range: log₁₀ space range of koff (units of s⁻¹).

• logkonb_range: log₁₀ space range of konb, Doi association rate in surrogate (units of s⁻¹).

• reach_range: linear range of reach values (units of nm)

• antigenconcen: Surrogate's internal antigen concentration in μM (default is DEFAULT_SIM_ANTIGENCONCEN).

• antibodyconcen: Surrogate's internal antibody concentration in μM (default is 1.0).

• CP: Surrogate's internal CP value (default is 1.0)

mutable struct Surrogate{S, T, U, V, W}

Surrogate parameters and data.

Fields

• surrogate_size: Number of points for each coordinate within the surrogate lookup table.

• itp: Interpolation of the surrogate lookup table.

• surpars: SurrogateParams used in the surrogate.

• simpars: Simulation parameters used in the surrogate.

Arguments (one of the following two):

• lutfile = the name of the file storing a surrogate to load.
• lutdata = AbstractArray representing the raw data points to build the surrogate from.

Notes:

• All fields can also be passed as a keyword arg.

build_surrogate_serial(surrogate_size::Tuple, surpars::SurrogateParams, simpars::SimParams;
                       terminator=VarianceTerminator())

Construct the data table array for a new surrogate by varying kon, koff, konb and reach.

Arguments:

• surrogate_size = a Tuple with (nkon,nkoff,nkonb,nreach) points to use.
• surpars = the physical parameters to use in the surrogate. It is strongly recommended to not change the default values of antigenconcen, antibodyconcen, or CP unless you really know what you are doing – these default values are implicitly assumed in other places.
• simpars = the simulation parameters to use (number of particles, simulations, domain size, etc).

Keyword Arguments:

• terminator, can be used to alter how the number of samples for each parameter set is determined. See VarianceTerminator for the default values.

save_surrogate(filename, surrogate_size, surpars::SurrogateParams, simpars::SimParams)

Create a JLD file with the given surrogate metadata.

Arguments:

• surrogate_size = a Tuple with (nkon,nkoff,nkonb,nreach) points to use.
• surpars = the physical parameters to use in the surrogate. It is strongly recommended to not change the default values of antigenconcen, antibodyconcen, or CP unless you really know what you are doing – these default values are implicitly assumed in other places.
• simpars = the simulation parameters to use (number of particles, simulations, domain size, etc).

fit_spr_data(surrogate::Surrogate, aligneddat::AlignedData, searchrange;
             optimiser = nothing, u₀ = nothing)

Find best fit parameters of the surrogate to the given data.

Notes:

• searchrange should be a BlackBoxOptim compatible vector of Tuples of the form:

    searchrange = [logkon_optrange,logkoff_optrange,logkonb_optrange,reach_optrange,logCP_optrange]

  or

    searchrange = [logCP_optrange]

  In the latter case the other parameter ranges are set equal to the range within the surrogate.
• Uses default_bivalent_optimiser by default if optimiser = nothing. Otherwise pass an Optimiser object.
• u₀ is an optional guess for the inital search point, methods may or may not use.
• Returns the best fit optimization object and the best fit (bio) parameters as a tuple.

optpars_to_physpars(optpars, antibodyconcen, antigenconcen,
                            surrogate_antigenconcen)

optpars_to_physpars(optpars, aligned_data::AlignedData, surrogate::Surrogate)

Converts parameters vector from BlackBoxOptim to physical parameters, converting the reach from simulation to physical values.

Notes:

• The reach is converted from the internal parameter value, εᵢ, to the physical value, εₑ, via

  \[ \varepsilon_e = \varepsilon_i \left(\frac{[AGC]_i}{[AGC]_e}\right)^{\tfrac{1}{3}},\]

  where $[AGC]_i$ is the internal simulator's antigen concentration and $[AGC]_e$ is the concentration used in experiments.
• Assumes these two concentrations have consistent units.

savefit(optsol, aligneddat::AlignedData, surrogate::Surrogate, simpars::SimParams,
        outfile)

Saves the data, simulated data with fit parameters, and fit parameters in an XLSX spreadsheet with the given name.

visualisefit(optsol, aligneddat::AlignedData, simpars::SimParams,
             surrogate::Surrogate, filename=nothing)

Plots fit between data and simulated curves using fitted parameters across a set of antibody concentrations.

Notes:

• filename = nothing if set will cause the graph to be saved.

surrogate_sprdata_error(optpars, surrogate::Surrogate, aligned_data::AlignedData)

This function takes a set of optimization parameters and interpolates a simulated kinetics curve from the surrogate, returning the $L^2$ error against the provided data.

update_pars_and_run_spr_sim!(outputter, logpars, simpars::SimParams)

Generate the biophysical parameters and run a forward simulation given parameters from the optimizer.

Arguments:

• outputter = an OutPutter instance for what simulation data to record
• logpars = vector of the five optimization parameters: [logkon,logkoff,logkonb,reach,logCP]
• simpars = SimParams instance, should be consistent with the surrogate