API - Convenience package

scaled_log_volume_prior(scale::Real = 1)

Create a prior generator (see AdaptiveOptions) that generates the following prior:

\[\text{prior}(\lambda) = - \frac{\text{scale}}{\text{length}(λ)^2} \cdot \left( \text{offset}^2 + \sum_{i=2}^{\text{length}(\lambda)} \left(\frac{\lambda_{i-1}}{\log_{10}(r_{i-1})-\log_{10}(l_{i-1})} - \frac{\lambda_{i}}{\log_{10}(r_{i})-\log_{10}(l_{i})}\right)^2 \right)\]

where $[l_i,r_i]$ are the intervals corresponding to $\lambda_i$.

minimizer_generator(optim_minimizer; 
	options = Optim.Options(g_tol = 1e-12, iterations = 2000), 
	gradient::Bool = false
)

Create a minimization function (f,∇f,initial_point) -> minimizing_point as specified in adaptive_dose_response_fit, using minimizers from Optim.jl (e.g. NelderMead() or LBFGS()).

If gradient = false, the gradient function ∇f is ignored, useful e.g. for adaptive_dose_response_fit where ∇f = nothing is internally passed as argument in some cases.

Examples

minimizer_generator(NelderMead())

minimizer_generator(LBFGS(), 
	options = Optim.Options(g_tol = 1e-6, iterations = 400), 
	gradient = true
)

mutable struct FittingCondition

Data type storing the necessary information for the common workflow of adaptive_dose_response_fit. Convenience constructors with recommended options are implemented. Note that all objects are "deepcopied" to avoid unwanted mutation.

Fields

• data: The FittingData object containing the dose-response data.
• replicates: Vector of FittingData objects that constitute the replicates of measured dose-response curves.
• grid: Initial K_τ grid that is adaptively refined.
• path: Fitting results are saved to path if path != "".
• options_1: AdaptiveOptions for the first run of adaptive_dose_response_fit.
• options_2: AdaptiveOptions for a second run of adaptive_dose_response_fit, e.g. to use a final, non-adaptive, gradient-based fit.
• minimizer_1: Minimization function for the first run of adaptive_dose_response_fit.
• minimizer_2: Minimization function for the second run of adaptive_dose_response_fit.
• result_concentrations: Concentrations to be used for the dose-response curve calculated from the fit result. This allows to obtain smooth result curves. If result_concentrations = nothing, the concentrations of data are used.

Convenience constructors

FittingCondition(data::FittingData, replicates = nothing; keywords...)

Manual specification of the FittingData object and the optional replicates. Recommended fitting options are predefined and path="" is set to avoid accidental creation of files.

FittingCondition(concentrations::AbstractVector, response_replicates::AbstractVector...; 
	keywords...)

Construct a FittingCondition from a concentration vector and response vectors (variable number of arguments). This automatically creates the main FittingData object, and the vector of FittingData objects for the replicates.

The main FittingData object uses the mean values of the responses together with the standard deviations as uncertainties. The uncertainty distributions are unnormalized logarithmic normal distributions:

(y,m,Δy)-> -(y-m)^2/Δy^2

Keywords

The keywords correspond to the struct fields, except for the additional scale keyword. Setting scale overwrites the objective field to :log_posterior and the prior_generator field to scaled_log_volume_prior for both options: options_1 and options_2.

The keyword defaults are:

• grid = create_grid(LogRange(extrema(concentrations)...,3))
• path = ""
• options_1 = AdaptiveOptions(objective = :lsq, offset = eps(), iterations = 30)
• options_2 = AdaptiveOptions(objective = :lsq, offset = eps())
• minimizer_1 = minimizer_generator(NelderMead())
• minimizer_2 = minimizer_generator(LBFGS())
• result_concentrations = nothing
• scale = nothing

fit_condition(condition::FittingCondition)

Obtain the results for a FittingCondition object (i.e. fitting the data).

Returns the AdaptiveResult object and saves the data (FittingCondition and AdaptiveResult objects) to FittingCondition.path if not FittingCondition.path = "".

fit_conditions(conditions)

Multithreaded application of fit_condition to a collection of FittingCondition objects (conditions).

load_results(path::AbstractString)

Load results and data as saved by fit_condition. Returns (result, data,replicates) as AdaptiveResult, FittingData and vector of FittingData objects.

function dr_base_plot(keywords...)

Function to return a modified dose-response base plot. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• xaxis = :log
• xlabel = "dilution"
• ylabel = "response"
• legend = :topleft
• density = 300

density_base_plot(keywords...)

Function to return a modified K_τ density base plot. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• xaxis = :log
• xlabel = "K_τ"
• ylabel = "density"
• legend = :topleft
• density = 300

data_options(keywords...)

Function to return a modified tuple of plotting keyword arguments for the FittingData object. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• seriestype = :scatter
• color = 1
• label = "mean values"
• yerrors = nothing

In addition, the following keyword ia available:

• filter_zeros = [true,false]: Select to omit data points from the plot when the x-value is zero (if true for first element of filter_zeros) or the y-value is zero (if true for second element of filter_zeros). See Measurement data - Plotting for further information.

replicate_options(keywords...)

Function to return a modified tuple of plotting keyword arguments for the replicate data. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• seriestype = :scatter
• color = :black
• opacity = 0.2
• label = "replicates"
• yerrors = nothing

In addition, the following keyword ia available:

• filter_zeros = [true,false]: Select to omit data points from the plot when the x-value is zero (if true for first element of filter_zeros) or the y-value is zero (if true for second element of filter_zeros). See Measurement data - Plotting for further information.

fit_options(keywords...)

Function to return a modified tuple of plotting keyword arguments for the DoseResponseResult response curve. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• seriestype = :path
• color = 2
• label = "fit result"

In addition, the following keyword ia available:

• filter_zeros = [true,false]: Select to omit data points from the plot when the x-value is zero (if true for first element of filter_zeros) or the y-value is zero (if true for second element of filter_zeros). See Measurement data - Plotting for further information.

density_options(keywords...)

Function to return a modified tuple of plotting keyword arguments for the DoseResponseResult density. Most Plots.jl keywords are available. By default, the following keyword arguments are set:

• seriestype = :path
• color = 2
• `fillalpha = 0.5
• label = "fitted density"

In addition, the following keyword ia available:

• volume_normalization = :log: Normalizes the grid weights for plotting. If :none the weights are not normalized, if :linear the weights are divided by their corresponding interval length and if :log the weights are divided by the interval length as it appears in a logarithmic plot. See Background: log-volume normalization for further information.

eu_options(n::Integer, bins = nothing; keywords...)

Function to return a modified tuple of plotting keyword arguments for the EpitopeUncertainty data series.

n must be equal to the number of levels (or larger) of the EpitopeUncertainty object that is plotted. If not bins = nothing the passed bins are marked in the plot with dashed lines (the color can be changed with the keyword bin_color). The bins must specify the indices of the gird intervals, e.g. [[1,2,3],[4,5], [9,10,11]]. The function select_indices can be used to obtain grid indices from grid domain ranges.

Most Plots.jl keywords are available. In addition, the following keyword arguments are available:

• colors = colormap("RdBu",n)[end:-1:1]: Array of colors (that Plots.jl accepts for the color keyword) corresponding to the different uncertainty levels. If the array contains less colors than uncertainty levels, the last color is repeated for the remaining levels.
• opacities = [1]: Array of opacities (number between 0 and 1) that correspond to the different uncertainty levels. Again, the last opacity is repeated if there are more uncertainty levels than opacities.
• reverse = false: If true the plotting order of the uncertainty levels is reversed. Since the uncertainty ranges are plotted on top of each other, this can become necessary when the EpitopeUncertainty constructor for samples is used, where larger levels correspond to larger uncertainty (as opposed to the bin-wise shifting constructor).
• volume_normalization = :log: Normalizes the grid weights for plotting. If :none the weights are not normalized, if :linear the weights are divided by their corresponding interval length and if :log the weights are divided by the interval length as it appears in a logarithmic plot. See Background: log-volume normalization for further information.
• hide_labels = true: If true the labels are omitted. Can become necessary when a large number of uncertainty levels is used.
• bins = nothing: Specifies the positions for the bin-markers (dashed lines). The bins must specify the interval indices, e.g. [[1,2,3], [5,6]]. Ideally, the bins used for the EpitopeUncertainty construction should be used. If bins = nothing, bin markers are omitted.
• bin_color = :gray: Color of the bin markers.

du_options(n::Integer; keywords...)

Function to return a modified tuple of plotting keyword arguments for the DoseResponseUncertainty data series.

n must be equal to the number of levels (or larger) of the DoseResponseUncertainty object that is plotted.

Most Plots.jl keywords are available. In addition, the following keyword arguments are available:

• colors = colormap("RdBu",n)[end:-1:1]: Array of colors (that Plots.jl accepts for the color keyword) corresponding to the different uncertainty levels. If the array contains less colors than uncertainty levels, the last color is repeated for the remaining levels.
• opacities = [1]: Array of opacities (number between 0 and 1) that correspond to the different uncertainty levels. Again, the last opacity is repeated if there are more uncertainty levels than opacities.
• reverse = false: If true the plotting order of the uncertainty levels is reversed. Since the uncertainty ranges are plotted on top of each other, this can become necessary when the EpitopeUncertainty constructor for samples is used, where larger levels correspond to larger uncertainty (as opposed to the bin-wise shifting constructor).
• hide_labels = true: If true the labels are omitted. Can become necessary when a large number of uncertainty levels is used.
• filter_zeros = [true,false]: Select to omit data points from the plot when the x-value is zero (if true for first element of filter_zeros) or the y-value is zero (if true for second element of filter_zeros). See Measurement data - Plotting) for further information.

bin_analysis_plot(results::Union{AdaptiveResult,Nothing},
	data = nothing,
	replicates = nothing; 
	keywords...
)

Create and return basic plots (dr_plot, density_plot) for the DoseResponseResult and the K_τ-density gird.

If results is an AdaptiveResult, both the fitted gird is plotted into the density plot and the corresponding curve is plotted into the dose-response plot.

If data is a FittingData object the data points are plotted into the dose-response plot. Similarly, if replicates is an array of FittingData objects, the data points are plotted as replicates in the dose-response plot.

Keywords

• dr_plot =dr_base_plot(): The base plot onto which the AdaptiveResult.result and the FittingData objects (data and replicates) are plotted. It can be any Plots.jl plot (e.g. another dose-response plot).
• density_plot =density_base_plot(): The base plot onto which the AdaptiveResult.grid is plotted. It can be any Plots.jl plot (e.g. another K_τ density plot).
• fit_arguments =fit_options(): Keyword argument tuple for the AdaptiveResult.result data-series.
• data_arguments =data_options(): Keyword argument tuple for the FittingData data-series.
• replicate_arguments =replicate_options(): Keyword argument tuple for the replicate data-series.
• density_arguments =density_options(): Keyword argument tuple for the AdaptiveResult.grid data-series.
• annotation_arguments = NamedTuple(): Keyword argument tuple for bin-annotations in the density plot. See below for further information.

Annotation bins

Annotation bins allow to annotate the density plot with the number of epitopes (in units of the density values) in the respective bin. The following keywords can be used for the annotation_arguments:

• annotation_bins = []: The bins as grid domain ranges, e.g. [[1e-10,1e-9], [1e-9,1e-8], [1e-5,1e-2]].
• annotation_size = 10: Size of the annotation font.
• annotation_offset = 0.05: Relative vertical offset from the top of the plot for the annotation labels. If a single number is provided, every other annotation is offsetted. If a length-matched vector of numbers is provided, each annotation is individually offsetted accordingly.
• annotation_color = :black: Color of the annotations.
• hover_points = false: If true, adds scatter-points with tool-tips for the Plotly/PlotlyJs backend.

peak_analysis_plot(results::AdaptiveResult,data = nothing; keywords...)

Create and return plots to analyze the effect of peaks in the K_τ density on the corresponding dose-response curve.

Returns (individual_dr_plot, cumulative_dr_plot, density_plot), where

• density_plot contains a plot of the K_τ-density with different colors for the different peaks (specified by the bins).
• individual_dr_plot contains the individual dose-response curves (color matched) that originate from the different peaks.
• cumulative_dr_plot contains the cumulative dose-response curves, i.e. dose-responses include the response increases caused by peaks with smaller K_τ. Again the curves are color matched with the peaks.

If data is a FittingData object the data points are plotted in the cumulative_dr_plot.

Keywords

• individual_dr_plot =dr_base_plot(): The base plot onto which the individual dose-response curves are plotted. It can be any Plots.jl plot (e.g. another dose-response plot).
• cumulative_dr_plot =dr_base_plot(): The base plot onto which the cumulative dose-response curves are plotted. It can be any Plots.jl plot (e.g. another dose-response plot).
• density_plot =density_base_plot(): The base plot onto which the K_τ-peaks are plotted. It can be any Plots.jl plot (e.g. another K_τ-density plot).
• fit_arguments =fit_options(): Keyword argument tuple for the AdaptiveResult.result data-series. Both color and label get overwritten by the colors keyword and the peak number (automatically determined).
• density_arguments =density_options(): Keyword argument tuple for the AdaptiveResult.grid data-series. Both color and label get overwritten by the colors keyword and the peak number (automatically determined).
• bins =peak_detection(results.grid, fill = false)[2]: The bins that define the K_τ-peaks as grid domain ranges, e.g. [[1e-10,1e-9], [1e-9,1e-8], [1e-5,1e-2]].
• colors = collect(1:length(bins)): The colors for the different bins.
• join_bins = true: If true, extends the bins if needed, s.t. there remains no gap between the bins.

uncertainty_plot(e_uncertainty::EpitopeUncertainty,
	d_uncertainty::DoseResponseUncertainty,
	grid::OneDimGrid; 
	keywords...
)

Create and return uncertainty visualizations (dr_uncertainty_plot, density_uncertainty_plot).

The estimated bounds of the DoseResponseUncertainty and EpitopeUncertainty are plotted as color-matched ribbons.

Keywords

• dr_plot =dr_base_plot(): The base plot onto which the AdaptiveResult.result and uncertainty ribbons are plotted. It can be any Plots.jl plot (e.g. another dose-response plot).
• density_plot =density_base_plot(): The base plot onto which the AdaptiveResult.grid and uncertainty ribbons are plotted. It can be any Plots.jl plot (e.g. another K_τ density plot).
• eu_arguments =eu_options(length(e_uncertainty.levels)): Keyword argument tuple for the EpitopeUncertainty data series. See EpitopeUncertainty - plotting for further information.
• du_arguments =du_options(length(d_uncertainty.levels)): Keyword argument tuple for the DoseResponseUncertainty data series. See DoseResponseUncertainty - plotting for further information.